home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Turnbull China Bikeride
/
Turnbull China Bikeride - Disc 1.iso
/
ARGONET
/
PD
/
GAMES
/
MONOPOLY.ARC
/
!DataSuite
/
Docs
/
DtLoadHelp
next >
Wrap
Text File
|
1994-04-28
|
47KB
|
916 lines
DataVoxLoader Help File.
========================
This module complements the DataVox Module by loading and storing in
RMA the data files for play. This module requires the DataVox module to
be memory resident to both be loaded and for it to work. Removing the
DataVox module while this one is loaded is a dangerous move and may cause
undefined results (Read a machine crash.) to occur.
The Concepts of DataLoad
========================
DataLoad provides a system of slots (or really logical sound channels)
to which files can be loaded and which can be related to real sound
channels. The mapping goes something like this:-
+------+
File -----> | Slot | ---------+
... | ... | | +------------+
... | ... | +----> | DataVox |
... | ... | --------------> | channel(s) |
... | ... | +----> +------------+
... | ... | ---------+
File------> | Slot |
+------+
The current version of DataLoad supports 1024 slots but this may be changed
at a later date and must not be counted on. Use the DataLoad_SlotsFree SWI
to find out how many slots are available instead.
The slots may be linked freely to as many or as few DataVox channels as
desired. Also any data written to a slot linked to a DataVox channel or
channels will be automatically passed on to those channels for you. This
means your application need never touch DataVox for most operations other
than claiming channels from it.
OSCLI Commands
==============
*DataLoadStatus
This command reads out the status of the logical channels in use in
DataLoad. It informs you of their address,length,assignment & name.
Syntax: *DataLoadStatus
*DataLoad_Load
This command loads files into DataLoad Slots for use. The Stereo flag
only has effect when the sample being loaded is stereo and not supplying
the DataVox channel to assign to causes the file to be simply loaded and
not assigned. Files that are recognised are Armadeus sample,DSEdit raw
sample,Amiga IFF 8SVX sample,Tracker sample,SUN audio file and ,of course,
the DataVox file. All bar the DataVox type III,Amiga IFF 8SVX,SUN audio
file & Tracker samples are recognised by their file type alone. The SUN
audio file,Amiga IFF 8SVX & Tracker samples are recognised by their file
contents. DataVox type III files are recognised by both their contents and
their filetype.
Syntax: *DataLoad_Load <filename> [DataVox channel] [Stereo Flag]
*DataLoad_Save
This command saves a DataLoad Slot back to a file. All settings held by
the slot will be saved with the file. The file will be a DataVox file.
Syntax: *DataLoad_Save <filename> <DataLoad Slot>
*DataLoad_AssignSlot
This command assigns a DataLoad Slot to a DataVox channel for play. If no
stereo flag is given and the sample is stereo then 0 is assumed.
Syntax: *DataLoad_AssignSlot <DataLoad Slot> <DataVox channel> [Stereo flag]
*DataLoad_DeAssignSlot
This command deassigns a DataLoad Slot from a DataVox channel.
Syntax: *DataLoad_DeAssignSlot <DataLoad Slot> <DataVox channel>
*DataLoad_ClearSlot
This command clears a DataLoad Slot - delinking DataVox from any
references to it and releasing the claimed space back into the RMA.
Syntax: *DataLoad_ClearSlot <DataLoad Slot>
SWI Commands
============
DataLoad_Load
On Entry :-
R0 file name/path pointer.
R1 channel. 0 for just load.
R2 Stereo bias if sample is stereo - 0 for Left 1 for Right.
On Exit :-
R0 Data Load Slot assigned.
R1 file format recognised string. (0 for not recognised.)
R2 preserved.
Errors :-
I do not understand the format of this file - it is too new.
No free DataLoad Slots available.
This is not a file.
Insufficient RMA Space to Load file.
Bad DataVox channel to load to.
Bad Stereo Assignment - 0 or 1 please.
Use :-
This SWI handles the loading of files into the RMA for use,allocating
them to a DataVox channel using the stereo flag if the sample being loaded
is stereo. It hands back to you a Slot number which is to be used to
reference the sample. This is for multi-tasking usage of the module and
it is expected that applications do *not* reference any slots but those
given to them. Also any filing system error can be reported back by this
routine as well as the errors listed above.
The loader code recognises and will interpret data from :-
DataVox files v1,v2 & v3. (All flags. surprise surprise! :-) )
Armadeus sample files. (Data type and sample speed)
DSEdit raw sample files. (Data type)
Tracker sample files. (Data type & Repeat points)
Amiga IFF 8SVX files. (Data type,stereo flag and sample speed)
SUN Audio files. (Data type and sample speed)
Any file not mentioned above will be loaded but no interpretation is made
on them and simple default values are assigned of :- Linear unsigned data type
,&2600 pitch,repeat block the whole file. So you can load and play text
files if you *really* want to. The Amiga IFF,Tracker & SUN file formats
are recognised by their internal contents and can be any file type. If the
file loaded is a compressed file (DataVox v3 supports this) then it
will *not* be assigned to the DataVox channel requested but it will be
loaded in memory. DataVox type III files will also be recognised by their
file contents and will be correctly loaded regardless of their filetype.
The number returned in R1 signals the kind of file recognised by
providing a pointer to a null terminated string that names the format loaded.
If zero is returned then the file format was unrecognised and default values
were be arranged.
N.B. Please note DataLoad assumes that the Tracker and IFF headers are
well defined chunks and can react strangely to corrupted headers. It
shouldn't crash but merely do unexpected things like play more data than
there is in the file resulting in RMA being played.
DataLoad_Save
On Entry:-
R0=Pointer to path/filename.
R1=DataLoad Slot number.
On Exit:-
R0,R1 preserved.
Errors:-
Bad DataLoad Slot.
Use:-
Not unsurprisingly this SWI saves a DataLoad Slot back to a file.
All flags etc set by the DataLoad_WriteData SWI will be saved in the file.
The files are always DataVox type 3 files. Also filing system errors can
be reported back as well as the error listed above. It also updates
DataLoad's copy of the full path name for the file. However if memory is
very tight this update may not be possible in which case the path given
by the last load/save operation to this slot will be retained. Accordingly
applications should not make any assumptions that this path will always be
updated.
DataLoad_AssignSlot
On Entry:-
R0 = DataLoad Slot to be assigned.
R1 = DataVox Channel.
R2 = Stereo assignment (0 or 1 as per DataLoad_Load)
On Exit:-
R0,R1,R2 preserved
Errors:-
Bad DataVox Channel to assign to.
Bad DataLoad Slot to assign.
Bad DataLoad Slot to assign - Block is compressed.
Bad Stereo flag - 0 or 1 please.
Use:-
This SWI assigns a DataLoad Slot to the DataVox channel specified.
All flags etc will be set up for you and the channel will be pointed at
the correct block of memory. More importantly DataLoad will take note
that this Slot is assigned to that DataVox channel and will ensure that
that channel is from here on in is pointing at the right memory. This is
important as it allows DataLoad to clean up after itself where needed
and ensure that DataVox is not pointing at an invalid block of memory.
Thus it is reccomended that you use this SWI for all references to
files held by DataLoad. Please note that if the sample being assigned is
not stereo then the stereo flag will be ignored.
DataLoad_DeAssignSlot
On Entry:-
R0 = DataLoad Slot to be deassigned.
R1 = DataVox Channel it was assigned to.
On Exit:-
R0,R1 preserved.
Errors:-
Bad DataVox Slot to deassign.
Bad DataLoad Slot to deassign.
This DataLoad Slot is not assigned to that DataVox channel!
Use:-
This SWI delinks a DataLoad slot from a DataVox channel when needed.
It also informs DataLoad that it does not need to ensure that that DataVox
channel is pointing to valid data anymore. All settings on the DataVox
channel are unset. If play synthesis is occuring when the de-assignment
is requested then play synthesis will be stopped before the slot's data
is junked.
DataLoad_ClearSlot
On Entry:-
R0=DataLoad Slot to clear.
On Exit:-
R0 preserved.
Error:-
Bad DataLoad Slot to Clear.
Use:-
This SWI clears a DataLoad slot releasing any memory held by it back
to the RMA and delinking any DataVox channels that reference that Slot.
Please note this function is only properely performed if the Slot was
linked using the DataLoad_AssignSlot SWI and not if an application did
the linking itself.
DataLoad_ReadData
On Entry:-
R0 Reason Code.
R1 DataLoad Slot to Read.
On Exit:-
R0,R1 preserved.
R2 Data wanted.
Errors:-
Unknown Read operation.
Bad DataLoad Slot to read.
Bad DataLoad Slot to read - no data linked to it.
Use:-
This is a general purpose reading SWI that allows you to read the
various settings of a DataLoad Slot. Precisely what data is returned is
governed by the reason code used and these are listed below.
Reason Code | Data Read
------------+-----------------------------------------------------------
0 | Data type of the slot. 0 Logarithmic,1 Linear Unsigned,
| 2 Linear signed & 3 Ulaw Logarithmic format.
|
1 | Timer flag of the slot. 1 for timed play ,0 otherwise.
|
2 | Reverse flag of the slot. 1 for reverse play ,0 otherwise.
|
3 | Fixed pitch flag. If this is set then the fixed pitch
| read by reason code 6 will be used when the slot is
| assigned to a DataVox channel.
|
4 | Stereo flag. 1 for a stereo slot. Only if this flag is set
| will the stereo flag passed to the Load & AssignSlot calls
| have any effect.
|
5 | Compressed flag. 1 for a compressed slot ,0 otherwise. If
| this flag is set then the slot can not be assigned to
| a channel.
|
6 | Pitch. This reads the pitch setting of a slot. The pitch
| given is a standard Arc one in the range 0-&8000 as used
| by the sound system. 0 indicates no fixed pitch and
| supercedes the fixed pitch flag.(if set) N.B. pitches
| returned by this SWI are always scaled to a 48 us system
| speed. If the current system speed is different from
| 48 us then this pitch will be different from the actual
| pitch in use.
|
7 | DataOffset - this gives the offset from the start of the
| slot block to the actual Data to be played.
|
8 | RepeatStart - this is an offset from the start of the
| slot block to the start of the repeat block.
|
9 | RepeatEnd - this is an offset from the start of the slot
| slot block to the end of the repeat block.
|
10 | Uncompressed Size - this is the size of the block
| uncompressed. If the file is already uncompressed then
| this will simply be the total size of the block and the
| total size of the file held in memory but if the file is
| compressed then this is the total size of the block of
| memory holding the file. This is for file compression
| as supported by DataLoad.
|
11 | UpCall Offset. This reads the offset from the start of the
| slot block to the slots UpCall code (if any). If UpCall
| code is present then this will always be word sized
| otherwise it is always zero.
|
12 | BufferStart. This returns the absolute memory address of the
| start of the slot block.
|
13 | BufferLength. This returns the total length of the slot
| block. This should be identical to the Uncompressed
| size but does not have to be. (It should never be smaller
| than it though for average cases.)
|
14 | SlotName. This returns a pointer to the null terminated
| leaf string of the slot name.
|
15 | 16 bit flag. 1 for a sixteen bit sample, 0 otherwise.
|
16 | FullSlotName. This returns a pointer to the null terminated
| full path, as given to DataLoad, for that slot.
This SWI should be the only way in which applications interrogate what the
settings of a DataLoad slot are.
DataLoad_WriteData
On Entry:-
R0 Reason Code.
R1 DataLoad Slot to Write.
R2 Data to Write.
On Exit:-
R0,R1,R2 preserved.
Errors:-
Unknown Write operation.
Bad DataLoad Slot to write - no data linked to it.
Bad DataLoad Slot to write.
Use:-
This is a general purpose SWI for setting a DataLoad Slots settings.
Any DataVox channels assigned to this Slot by the AssignSlot SWI will be
automatically updated to reflect the new settings. Each reason code has
its own extra error message associated with it and the reason codes &
error messages are :-
Reason Code | Comment
------------+-----------------------------------------------------------
0 | Writes the Slots data type. (0,1,2 or 3)
| Error:- Bad DataType to Write.
|
1 | Sets the Slots timed flag. (0 or1)
| Error:- Bad Timer Flag to Write.
|
2 | Writes the Slots reverse flag. (0 or 1)
| Error:- Bad Reverse Flag to Write.
|
3 | Writes the Slots fixed pitching flag. (0 or 1)
| Error:- Bad Pitch Flag to Write.
|
4 | Writes the Slots stereo flag. (0 or 1)
| This automatically delinks all DataVox channels from this
| slot.
| Error:- Bad Stereo Flag to Write.
|
5 | Writes the Slots compressed flag. (0 or 1)
| Error:- Bad Compressed Flag to Write.
|
6 | Writes the Slots pitch. (0-&8000)
| Error:- Bad Pitch to Write.
|
7 | Writes the Slots DataOffset. (32-Block Size)
| Error:- Bad Data Offset to Write.
|
8 | Writes the Slots Repeat Start Offset. (32-Block Size)
| Error:- Bad Repeat Start Offset to Write.
|
9 | Writes the Slots RepeatEnd Offset.
| (Repeat Start Offset-Block Size)
| Error:- Bad Repeat End Offset to Write.
|
10 | Writes the Slots Uncompressed Size. (32-What Ever)
|
11-14 | Reserved for future expansion.
|
15 | Writes the Slots sixteen bit flag. (0 or 1)
| Error:- Bad 16 bit Flag to Write.
|
16 | Reserved for future expansion.
DataLoad_SlotsFree
On Entry:-
R0,R1 Undefined.
On Exit:-
R0 No. Unallocated channels.
R1 No. Allocated channels.
Errors:-
none.
Use:-
This returns the number of Allocated and Unallocated channels
maintained by DataLoad. This allows applications to query if sufficient
slots are available for use.
DataLoad_CreateSlot
On Entry:-
R0 Pointer to Name.
R1 Size of Data.
R2 Type of Data.
On Exit:-
R0 Slot No.
R1 Ptr to Start of Buffer. (first byte of data after header data.)
R2 Ptr to End of Buffer.
Errors:-
No free slots to Create Slot into.
Insufficient RMA space to Create Slot.
This is a silly size to Create a Slot to!
Use:-
This SWI allows you to create an empty slot for use. This is primarily
intended for Sound Samplers to use but anyone who needs to create a Slot
can use this. The Slot is pre-initialised to an appropriate set of
values and is cleared out to 'zero sound'. Exactly what the slot is filled
with is decided by the Data Type. Please note that due to the way the RMA
allocates blocks the delivered space may be a few bytes *larger* (never
smaller) than requested. NB The size passed is assumed to be *sans*
header and sufficient space for a header will be automatically added to
this size before allocation occurs.
DataLoad_ExtendSlot
On Entry:-
R0 DataLoad Slot to extend.
R1 Signed integer of amount to extend.
On Exit:-
R0 & R1 preserved.
Errors:-
Bad DataLoad Slot to Extend.
Bad DataLoad Slot to Extend - no data linked to it.
Bad Size to Extend by! This makes the slot smaller than header size!.
No Room in RMA for Block Extension.
Use:-
This allows you to alter the size of an existing slot to whatever
is needed. If the Slot is extended in size then the extended area is
automatically cleared to 'zero-sound' for you. If any channels are
linked to this slot then they are unlinked automatically. Please note that
any size given is expected to be *inclusive* of the 32 bytes of header
space.... Changes are currently *not* echoed to any assigned channels....
N.B. This SWI assumes you know what you are doing and does *not* adjust
most of the header information. Therefore care should be exercised in its
use.... It does perform clipping though to ensure that certain offsets are
still valid.
N.N.B. Using an adjust size of 0 will cause the RMA to reshuffle the block
in memory, allowing you to force the RMA to try and relocate the block as
low in memory as possible. Care must be taken though to ensure this trick
is only used when sufficient free memory *below* the block is available
else the block could be shuffled up higher in the RMA.
DataLoad_Version
On Entry:-
R0 Undefined
On Exit:-
R0 Version Number * 100
Errors:-
none
Use:-
Fairly self explanitory really.
DataLoad_QueryAssign
On Entry:-
R0 DataVox channel to query.
On Exit:-
R0 Slot number attached to that channel. (0 if none)
Errors:-
Bad real channel to query.
Use:-
This allows applications to intelligently decide whether or not an
allocation call is needed. This is because allocation calls are time
intensive compared to this SWI and an application may wish to avoid
unecessary delays where possible.
Error Messages
==============
The Error range begins at &806180, ends at &8061BF, and here is the error
message list. This list only comprises errors generated *by* DataLoad, errors
from filing systems will be reported back as appropriate too.
Error # | Error Message
--------+-------------------------------------------------------------
0 | DataVox is not loaded in memory. I cannot initialise!
1 | DataLoad is in use.
2 | Bad DataVox channel to assign the file to.
3 | Bad Stereo flag.
4 | Bad Slot number to save.
5 | Insufficient RMA Space to Initialise!
6 | Unknown DataLoad operation.
7 | I do not understand the format of this file - it is too new.
8 | No free DataLoad Slots available.
9 | This is not a file.
10 | Insufficient RMA Space to Load file.
11 | Bad DataVox channel to load to.
12 | Bad Stereo Assignment - 0 or 1 please.
13 | Bad DataLoad Slot.
14 | Bad DataVox Channel to assign to.
15 | Bad DataLoad Slot to assign.
16 | Bad DataLoad Slot to assign - Block is compressed.
17 | Bad Stereo flag - 0 or 1 please.
18 | Bad DataVox Slot to deassign.
19 | Bad DataLoad Slot to deassign.
20 | This DataLoad Slot is not assigned to that DataVox channel!
21 | Bad DataLoad Slot to Clear
22 | Unknown Read operation.
23 | Bad DataLoad Slot to read.
24 | Bad DataLoad Slot to read - no data linked to it.
25 | Unknown Write operation.
26 | Bad DataLoad Slot to write.
27 | Bad DataLoad Slot to write - no data linked to it.
28 | Bad DataType to Write.
29 | Bad Timer Flag to Write.
30 | Bad Reverse Flag to Write.
31 | Bad Pitch to Write.
32 | Bad Data Offset to Write.
33 | Bad Repeat Start Offset to Write.
34 | Bad Repeat End Offset to Write.
35 | Bad Stereo Flag to Write.
36 | Bad Compressed Flag to Write.
37 | Bad Pitch Flag to Write.
38 | Bad 16 bit Flag to Write.
39 | No free slots to Create Slot into.
40 | Insufficient RMA space to Create Slot.
41 | This is a silly size to Create a Slot to!
42 | Bad datatype to Create a Slot with!
43 | Bad DataLoad Slot to Extend.
44 | Bad DataLoad Slot to Extend - no data linked to it.
45 | Bad Size to Extend by! This makes the slot smaller than header
| size!
46 | No Room in RMA for Block Extension.
47 | Bad real channel to query.
DataVox File Format
===================
Consists of eight header words then pure sample data in the newest format.
However the two older formats are supported for load only and are noted here
as well. Any bits whose function is not specifically stated should always be
cleared to zero as they are reserved for future expansion. Filetype &108 is
the officially allocated type for these files.
File Format 1
-------------
Byte | Comment
-----+------------------------------------------
0 | Data Type. Currently in the range 0-2.
| 0 Log, 1 Linear Unsigned & 2 Linear
| Signed.
1 | Flag Byte. Bit 0 set for timed unset for
| untimed.Bit 1 set for fixed pitching 0
| for normal play.
2-3 | 16 bit pitch value for sample.
4 | 32 bit offset from header start to data.
| 8 for this format.
8+ | Sample data.
File Format 2
-------------
Byte | Comment
-------+------------------------------------------
0 | Data Type. Currently in the range 0-2.
| 0 Log, 1 Linear Unsigned & 2 Linear
| Signed.
1 | Flag Byte. Bit 0 set for timed unset for
| untimed.Bit 1 set for reversed play 0
| for normal play. Bit 2 set for fixed
| pitching 0 for normal.
2-3 | 16 bit pitch value for sample.
4-7 | 32 bit offset from header start to data.
| 16 for this format.
8-11 | 32 bit offset to start of repeated data.
12-15 | 32 bit offset to end of repeated data.
16+ | Sample data.
File Format 3
-------------
Byte | Comment
-------+-----------------------------------------
0 | Data Type. Currently in the range 0-3.
| 0 Log, 1 Linear Unsigned, 2 Linear
| Signed & Ulaw Logarithmic.
1 | Flag Byte.
| Bit 0 set for timed play.
| Bit 1 set for reversed play.
| Bit 2 set for fixed pitching.
| Bit 3 set for stereo sample.
| Bit 4 set for compressed sample.
| Bit 5 set for 16 bit data.
2-3 | 16 bit pitch value for sample.
| If bit 15 is set then the number is a
| negative number with the top 16 bits
| assumed to be &FFFF.
4-7 | 32 bit offset from header start to data.
| Usually 32 for this format.
8-11 | 32 bit offset to start of repeated data.
12-15 | 32 bit offset to end of repeated data.
16-19 | 32 bit "DVOX" ID Word. (&584F5644)
20-23 | 32 bit Version Number. (3)
24-27 | 32 bit Offset to Upcall Code.
28-31 | 32 bit Uncompressed File Size.
32+ | Sample data.
Formats 1 & 2 are provided purely for compatability reasons whereas
Format 3 is the format currently used. The layout of the file must be :-
+----------+--------+-----------------+
| Header | UpCall | Sample |
| 32 bytes | Code | Data |
+----------+--------+-----------------+
The UpCall code must be between the sample data and the header information
and it is the Editors responsibility to ensure that the UpCall code is
kept valid if the Block size is altered.
If the sample is stereo then the file looks something like this :-
+----------+--------+---------------+---------------+
| Header | UpCall | Sample | Sample |
| 32 bytes | Code | Data Part A | Data Part B |
+----------+--------+---------------+---------------+
Where part A is refered to by Stereo flag setting 0 & part B referred to
as Stereo flag 1. Please note to determine the boundary between part A &
part B the following calculation is used :-
Part A Start Offset :- Data Offset
End Offset :- Data Offset + ((Length of Block - Data Offset)/2)
Part B Start Offset :- Data Offset + ((Length of Block - Data Offset)/2)
End Offset :- Length of Block
If the sample is a 16 bit one then the sample data is further sub-divided
into two sections :-
+---------------+--------------+
| Sample Data | Sample Data |
| high bytes. | low bytes. |
+---------------+--------------+
Each of these sections is exactly half of the original size of the data
section. Of the two sections only the high bytes will be actually played
as the archimedes sound system is currently capable of only outputing
eight bit samples. Other than this change the data area is treated
identically....
Also an area is being reserved for applications. This area will be totally
ignored by DataLoad but may be used by applications to add `supplemental`
data that they feel the sample needs. The idea is data like, date of
sampling, textual note as to what the sample is, etc... will be stored
here. In no way is *anything* required to be stored here however. It is
a chunk based area where each chunk is headed by two words.
Chunk format :-
Byte | Comment
-----+-----------------------------------------------------------------
0-3 | An ID word identifying what the chunk is. All chunk ID's should
| be registered with me to avoid name collision.
4-7 | A length word. Relative to the start of the chunk this should be
| word sized length of the chunk in bytes. All chunks *must* be
| word sized.
8+ | Chunk data. This is entirely arbitrary to the chunk....
This area is placed between the header data and before the UpCall code (if
any is present.) otherwise it is before the Sample Data. Like so:-
+----------+-------------+--------+-----------------+
| Header | Application | UpCall | Sample |
| 32 bytes | Area | Code | Data |
+----------+-------------+--------+-----------------+
Currently defined chunks are:-
Chunk ID | Comment
-----------------+----------------------------------------------------
`Date` &65746144 | A five byte time detailing the date of sampling. The
| format of the bytes is as per OS_Word 14,3.
`Name` &656D614E | A null terminated string detailing the long name of
| the sample.
`Note` &65746F4E | A null terminated textual string detailing something
| about the sample.(Intended to store human readable
| interesting data.)
Next the Upcall area is organised into two distinct types. There is the
`custom` uneditable type that has been presumably created for a special
purpose and there is the editable type. The two are distinguished by the
first word of the upcall area being a `UpCl` or &6C437055. If this word
is present the next few words are in a special format. This looks like
this :-
Bytes | Comment
-------+----------------------------------------
0-3 | ID Word `UpCl`.
4-7 | Offset to entry point for UpCall code.
8-11 | ID Word (for Editors)
11+ | Version Dependant Jump table.
The offset(s) contained in the code should (bar internal to your code) all
be relative to byte 0 or the start of the upcall area. The ID word is purely
for Editors to be able to identify the type of upcall code being used. The
word is divided into two 16 bit parts. The high 16 bits (bits 31-16) contain
the *type* of upcall code contained. This should be a number in the range
0-65535 and dictates how the next few words should be interpreted. The low
16 bits is the minor version number * 100. This allows for each major type
of upcall code to have its own version type and history as required.
After the first three words the next few words format is totally dictated
by the major version number. Editors encountering a major version number
that they don't understand should refuse to allow editing of the upcall
code. (Removal yes but not editing.) There is currently only one defined
upcall type but again I expect this to change. To register your particular
type of upcall code you must send all the details and some example source
code of it (and some examples would be nice) to me. I will then assign it a
major type number and note the neccesary details that an editor will need to
know here. A short descriptive name of the purpose of the upcall code is
needed too.
Some general points to remember about Upcall code are that the code is
being called under interupts so re-entrancy is vital. Basically stacking
R0-R12 & R14 along with keeping references to workspace to a minimum in the
Upcall update code will ensure this. Of course calling SWI's from the
primary update code is ill advised. Only do that if you really *must*! Other
than that coding UpCall code with all the restrictions that interupt code
has is the best course.
Upcall types:-
--------------
+--------------+---------------------------------------------------------+
|Version No.s | Comment/Notes. |
+------+-------| |
|Major | Minor | |
+------+-------+---------------------------------------------------------+
| 0 | 0.04 | Description - Table Sequenced Song. |
| | | Uses - 4 extra header words. |
| | | bytes 12-15 are the offset to a Pitch Table which is |
| | | laid out two words per entry. |
| | | Word 0 16 bit number - total number of pitches held in|
| | | the table. 0 indicates no pitches are held. The top |
| | | 16 bits reserved for future expansion. |
| | | Word 1 The system speed in micro seconds this table is|
| | | calibrated for. All 24 other bits reserved for |
| | | future expansion. |
| | | Word n*2 (where n is a index number) is the 16 bit |
| | | pitch. |
| | | Word n*2+1 is the internal format phase accumulator |
| | | pitch. (IE the value returned from SWI "Sound_Pitch"|
| | | shifted down by 16 bits.) |
| | | Bytes 16-19 are the offset to a Start Address Table |
| | | which is laid out one word per entry. |
| | | Word 0 is a 16 bit number - total number of Start |
| | | Addresses held. Top 16 bits reserved. |
| | | Word n (where n is an index number) is the 32 bit |
| | | offset from the start of data to the actual start |
| | | for this entry. |
| | | Bytes 20-23 are the offset to an End Address Table |
| | | which is laid out in an indentical fashion to the |
| | | start address table. |
| | | Bytes 24-27 are the offset to the Sequence Table. |
| | | Two words per entry. |
| | | Word 0 16 bit number - total number of sequences |
| | | held. top 16 bits reserved. |
| | | Word 1 reserved for future expansion. |
| | | Word n*2 (where n is an index number) :- |
| | | top 16 bits - Start Address index number |
| | | low 16 bits - End Address index number |
| | | Word n*2+1 :- |
| | | top 16 bits - Reserved for future expansion. |
| | | low 16 bits - Pitch index number. |
| | | This is a very simple system designed purely for speed.|
+------+-------+---------------------------------------------------------+
Finally DataLoad allows for the concept of a compressed file. The layout
of a compressed file is :-
<------------File Length-------------->
<------------Block Length in Memory-------------->
+----------+--------+--------+--------+- - - - - +
| Header | UpCall | Header | Sample | |
| 32 bytes | Code | Byte | Data | |
+----------+--------+--------+--------+- - - - - +
<---Data Offset---->
The data offset points to a header byte that identifies the compression
method used on the data ,followed by the compressed sample data. DataLoad
does not have any compression routines in it and will refuse to allow a
compressed sample to be linked to a DataVox channel. Instead it is the
applications responsibility to uncompress the file first. If you wish
to write a compression routine and want to incorporate it with DataLoad
please register such a routine with me so that you do not use conflicting
header bytes that may have been allocated to another compression routine.
Currently no compression routines have been defined but I expect this
to change real soon...
Version History
+---------+--------------------------------------------------------------+
| Version | Comments. |
+---------+--------------------------------------------------------------+
| 1.00 | The complement to the DataPlayerModule DataLoad maintains up |
| | eight files in the RMA and attaches them appropriately to |
| | the DataVoxPlayer channels. (16-Feb-1991) |
| 1.01 | Added to the loader SWI the added commands for the modules |
| | file type. The file type stores in it the pitch,type,timing |
| | control,offset to data and data itself for a Noise. Filetype|
| | &401 is used. (16-Feb-1991) |
| 1.02 | Corrected a loading routine error that didn't release memory |
| | before it claimed more memory resulting in a rapidly |
| | increasing RMA Space... (16-Feb-1991) |
| 1.03 | Added the save SWI to store sounds back to disk...(suprise, |
| | surprise..) (18-Feb-1991) |
| 1.04 | Added a nice wee OSCLI command interface to allow the loading|
| | ,saving and clearing of files from or to DataChannels. |
| | (19-Feb-1991) |
| 1.05 | Updated the save code to give more meaningful errors (It was-|
| | n't before). (05-Apr-1991) |
| 1.06 | Updated the save so that it passes the errors from the filing|
| | system ,which are the most meaningful! (21-Apr-1991) |
| 1.07 | Added the ability to load Armadeus samples and make a reason-|
| | able approximation of their playing speed. Also now loads |
| | DSEdit raw sound files but it makes no guess as to their |
| | playing speed - this must be set by the user. (19-May-1991) |
| 1.08 | Corrected an embarrasing error with the DataLoad command that|
| | caused only DataChannel 1's pitch to affected when loading |
| | correctly typed files. (08-Jun-1991) |
| 1.09 | Corrected to work with the non-standard OS_File behaviour of |
| | Arcfs v0.30 which played silly buggers with the load |
| | address in R2 from OS_File 255. Reduced code size by a |
| | whole 4 bytes! Amazing huh for fixing an error I shouldn't |
| | have had to in the first place! (06-Jul-1991) |
| 1.10 | Finally got a working formula for kHz to pitch mapping and |
| | have corrected DataLoad to use it. Now it always maps the |
| | right speed. (15-Jul-1991) |
| 1.11 | Updated to work with version 3.07 of DataPlay. It will now |
| | save/restore the reverse flag and the repeated area |
| | settings. Also due to the new facilities of DataPlay it |
| | reliably copes with Armadeus files. (31-Aug-1991) |
| 1.12 | Fixed an error in the Armadeus file loading code. I wonder |
| | who forgot about little things like channel numbers... :-) |
| | (31-Aug-1991) |
| 1.13 | Added the FindBuffer SWI to allow applications using DataLoad|
| | to manipulate the stored data directly. (01-Sep-1991) |
| 1.14 | Fixed an error in the Loading Code that dealt with Format 2 |
| | files. (08-Sep-1991) |
| 1.15 | Extended the Save code to cope with the extended version of |
| | SetRepeat SWI. (08-Sep-1991) |
| 1.16 | Fixed a intermittant error in the Save code that was causing |
| | errors when doing file loads. (16-Oct-1991) |
| 2.00 | The all new singing and dancing version of Dataload. It |
| | supports mulitple files and a whole lot more... |
| | (04-Nov-1991) |
| 2.01 | Fixed the IFF 8SVX load code to correctly interpret the speed|
| | of the file. (05-Nov-1991) |
| 2.02 | Optimized the Restore Code to only use Pitch independance |
| | neccessary so that in normal use all 16 bits of the Pitch |
| | are significant.(Otherwise only eight are...) (08-Nov-1991)|
| 2.03 | Corrected the IFF load code to correctly recognise Stereo & |
| | non-stereo samples. Also corrected the load scan to make it|
| | more efficient. (08-Nov-1991) |
| 2.04 | Added the QueryAssign SWI to allow applications to do 'smart'|
| | decisions about whether or not to use the AssignSlot SWI. |
| | (12-Nov-1991) |
| 2.05 | Added SUN audio file load code and corrected a possible error|
| | in IFF file load and the Create Slot SWI. (15-Nov-1991) |
| 2.06 | Altered the PitchWrite code to stop uneccessary pitch conver-|
| | sions. (19-Nov-1991) |
| 2.07 | Correct an error in the range checking of the ClearSlot SWI. |
| | Because of this error some slot numbers passed to the SWI |
| | could lock the machine up. (20-Nov-1991) |
| 2.08 | Corrected a minor, non fatal, error in the load code that |
| | caused it to refuse to load some samples claiming a lack |
| | of RMA space! Guess who was letting a V flag slide.... |
| | I never knew a CMP could set the V Flag.... (16-Dec-1991) |
| 2.09 | Added 16 bit data support with a 16 bit flag. If set the |
| | sample data is treated as described in the file format |
| | section. (29-Dec-1991) |
| 2.10 | Added the support needed for the UpCall code format. |
| | (16-Jan-1992) |
| 2.11 | Corrected a minor error in the DSEdit load code. Also altered|
| | it to not call its own SWI's except by BL. (2-Feb-1992) |
| 2.12 | Corrected a R12 corruption error in the OSCLI interface. I |
| | knew I shouldn't have listened to Julian on those mods he |
| | suggested.... :-) (12-Feb-1992) |
| 2.13 | Received the SWI, Error and Wimp message chunk allocation. |
| | Hardcoded these values in. (18-Apr-1992) |
| 2.14 | Fixed up an error or three in CreateSlot code. Corrected a |
| | mistake in the Save code. Adjusted the module to use the |
| | freshly allocated Filetype number of &108. (19-May-1992) |
| 2.15 | Corrected the initialisation procedure to check for the |
| | correct version of DataVox as well as it's prescense. |
| | (15-Jun-1992) |
| 2.16 | Minor fix to CreateSlot - R1 was returning a position 28 |
| | bytes higher than it should be. (21-Jun-1992) |
| 2.17 | Fix to Extend Slot - now it won't clear out the entire slot |
| | when extending a block, only the new extension area. |
| | All file paths are stored as full ones now. ReadData type |
| | 16 (ReadFullName) has been added to reflect this change. |
| | DataVox Type III files are now recognised by both the |
| | filetype and by word 5 of the header, thus DvoxIII files |
| | will be correctly loaded regardless of filetype. |
| | (27-Aug-1992) |
| 2.18 | Due to the RMA Memory Manager behaving weirdly the zero size |
| | has had to be removed. It now quietly ignores the call. |
| | (04-Sep-1992) |
| 2.19 | Thanks to some information from Acorn regarding a typing |
| | error in the PRMs the ExtendSlot SWI now works *properly* |
| | inclusive of the zero size 'RMA re-shuffle' trick. |
| | (14-Sep-1992) |
| 2.20 | Fixed an error in Type III file loading for when the header |
| | has a zero, and thus badly formed, uncompressed size field.|
| | Corrected CreateSlot to correctly set the uncompressed size|
| | as it should. (24-Sep-1992) |
| 2.21 | Corrected an error in the load routine introduced by the |
| | bug 'fix' of 2.20 on the uncompressed header size. Thank |
| | goodness for DDT's ability to step through modules. Fixed |
| | Extend Slot to correctly clear out the sample extension to |
| | the proper 'zero sound' value for the DataType. |
| | (12-Oct-1992) |
| 2.22 | Add the original format type identifier to DataLoad_Load. |
| | Now front-ends can know what format the sample was |
| | originally for information displays. (29-Oct-1992) |
| 2.23 | Minor changes to allow negative pitches in Type III files. |
| | (26-Nov-1992) |
| 2.24 | Fixed the save SWI to record the new absolute path the file |
| | is being saved to. (21-Dec-1992) |
| 2.25 | Fixed a minor bug in the load SWI pertaining to incorrect |
| | handling of the stereo flag in type III files on 'load and |
| | assign' operations. (25-Jan-1993) |
| 2.26 | Corrected an error with Type III compressed file handling. |
| | (06-Dec-1993) |
| 2.27 | Adjusted the SWI return code to correctly reset flags when |
| | exiting. (14-Dec-1993) |
| 2.28 | Corrected a bug in the name handling routines. Altered the |
| | default file loading to more useful values. Adjust the IFF |
| | handling code to not get confused over RIFF files. |
| | (02-Jan-1994) |
| 2.29 | Adjust the SUN audio file handling to cope with the strange |
| | header variant that gives an incorrect data size. |
| | (03-Jan-1993) |
+---------+--------------------------------------------------------------+
